home *** CD-ROM | disk | FTP | other *** search
/ MacHack 1997 / MacHack 1997.toast / Hacks / Hacks ’96 / Roaster-Java-WA-HTTP-CGI hack / Protect WA plugin / Interfaces / module.h < prev    next >
Encoding:
C/C++ Source or Header  |  1996-06-22  |  11.7 KB  |  337 lines  |  [TEXT/MPS ]
  1. #ifndef MODULE_H
  2. #define MODULE_H
  3.  
  4. /* This flag controls application code used to help debug plugin modules,
  5.  * as well as debugging code within a module itself.
  6.  */
  7. #ifndef ModuleDebug
  8. #define ModuleDebug 1
  9. #endif
  10.  
  11.  
  12. #ifndef MODULE_R_H
  13. #include "Module.r.h"
  14. #endif
  15.  
  16. #ifndef CKIDEFS_H
  17. #include "ModuleSupport.h"
  18. #endif
  19.  
  20.  
  21. /* This is the common include file for both Plug-in modules and an application
  22.  * which makes use of them.  It defines the data structures which are visible
  23.  * to a module.  This file contains only application-independent data
  24.  * structures; data structures specific to a particular application must be
  25.  * defined elsewhere.
  26.  */
  27.  
  28.  
  29. /* When a module is first loaded, we assign it a ModuleID which is then used
  30.  * to refer to that module as long as it remains loaded.  This is simply an
  31.  * index into a table of loaded modules.  Legal values are always positive;
  32.  * zero or negative ModuleIDs indicate nil or error conditions.  When a
  33.  * module is unloaded, its ModuleID can be reused.
  34.  * 
  35.  * Note that this is _not_ the module's permanent unique ID (the 32-bit value
  36.  * stored in the module's 'MDdf' resource).  It is a 16-bit tag used to refer
  37.  * to a loaded module during a particular session of Arrange.
  38.  */
  39. typedef Short ModuleID;
  40.  
  41.  
  42. struct ModuleParamBlock;
  43. typedef struct ModuleParamBlock ModuleParamBlock;
  44.  
  45.  
  46. /* The following declarations are required to allow modules to be compiled
  47.  * using Think C, which has different parameter-passing conventions than
  48.  * MPW C: namely, parameters are pushed in the opposite order (left-to-right
  49.  * instead of right-to-left), 2-byte parameters are not expanded to 4 bytes,
  50.  * and the callee is responsible for removing the parameters from the stack.
  51.  * 
  52.  * By appending ", ..." to the end of each parameter list, we force Think C
  53.  * to use the MPW-style calling conventions (except for the expansion of
  54.  * 2-byte values to 4 bytes).  This is done using the ENDP macro, which
  55.  * expands to the empty string except when compiling under Think C.  To
  56.  * force 2-byte values to be expanded to 4 bytes, we define aliases for
  57.  * ModuleID, Boolean, and Short to be used in parameter declarations.
  58.  */
  59. #ifdef __SC__
  60.     #define ENDP , ...
  61.     typedef long pModuleID;
  62.     typedef long pBoolean;
  63.     typedef long pShort;
  64. #elif defined (__MWERKS__)
  65.     #define ENDP
  66.     typedef long pModuleID;
  67.     typedef long pBoolean;
  68.     typedef long pShort;
  69. #else // ndef __SC__
  70.     #define ENDP
  71.     typedef ModuleID pModuleID;
  72.     typedef Boolean  pBoolean;
  73.     typedef Short    pShort;
  74. #endif // else ndef __SC__
  75.  
  76.  
  77. /* Struct defining the QuickDraw global variables - used as a field in
  78.  * ModuleSysInfo (below).
  79.  */
  80. #if !UniversalIncludes
  81. struct QDGlobals
  82.     {
  83.     char privates[76];
  84.     long randSeed;
  85.     BitMap screenBits;
  86.     Cursor arrow;
  87.     Pattern dkGray;
  88.     Pattern ltGray;
  89.     Pattern gray;
  90.     Pattern black;
  91.     Pattern white;
  92.     GrafPtr thePort;
  93.     }; // QDGlobals
  94. #endif // if !UniversalIncludes
  95.  
  96.  
  97. // This struct contains info about a currently loaded Plugin module.
  98. struct ModuleInfo
  99.     {
  100.     Short    vers;           // Version number for this record (currently 1).
  101.     FSSpec   file;       // File containing the module.
  102.     Short    fileRef;    // Refnum for file's resource fork.
  103.     Short    defID;       // ID of the module definition resource.
  104.     ModuleID    modID;       // ModuleID assigned when this module was loaded.
  105.     const void* appInfo; // Application-specific info (nil if unused).
  106.     
  107.     // Information copied from the ModuleDef record.
  108.     uShort flags;            // ModuleFlags values (set unused bits to zero).
  109.     char name[32];          // Unique name (0-terminated) for this module.
  110.     uInteger id;         // Unique ID (registered with CKI) for this module.
  111.     uInteger modVers;    // Module version.
  112.     Short rootCodeID;    // ID of the root code resource ('MDcd') for this module
  113.                                // (code resource containing the module's boot function);
  114.                                // value is relative to the ID of the 'MDdf' resource.
  115.                                // -1 if module has no boot function.
  116.     }; // ModuleInfo
  117.  
  118.  
  119. // This struct specifies an entry point within a loaded module.
  120. struct ModuleEntryPoint
  121.     {
  122.     ModuleID module; // ID of the module owning this entry point; 0 indicates
  123.                           // a "nil" value.
  124.     Short    rsrcID; // ID of the resource ('MDcd') containing the entry point.
  125.     uInteger offset; // Entry point offset within the code resource.
  126.     
  127.     Boolean IsNil()  { return module == 0; }
  128.     Boolean NotNil() { return module != 0; }
  129.     
  130.     Boolean operator==(const ModuleEntryPoint &entry) const;
  131.     Boolean operator!=(const ModuleEntryPoint &entry) const { return !operator==(entry); }
  132.     }; // ModuleEntryPoint
  133.  
  134.  
  135. // This struct provides information about the machine on which we are running.
  136. struct ModuleSysInfo
  137.     {
  138.     Short   vers;            // Version number for this record (currently 2).
  139.     Short   pad;            // Unused (always 0).
  140.     Integer sysVers;        // System software version number.
  141.     Boolean hasFPU;        // True if a floating-point coprocessor is present.
  142.     Boolean hasColorQD;    // True if Color QuickDraw is available.
  143.     Rect      screenBounds;// Bounds of the monitor containing the menu bar.
  144.     FSSpec  sysFolder;    // Location of the system folder.
  145.     FSSpec  prefsFolder;    // Location of the application's preferences folder,
  146.                                 // or the system folder if the app doesn't create
  147.                                 // a custom prefs folder.
  148.     
  149.     // Fields added in version 2 of ModuleSysInfo record:
  150.     
  151.     QDGlobals *qd;            // pointer to QuickDraw globals
  152.     }; // ModuleSysInfo
  153.  
  154.  
  155. /* This enum describes a particular build of the application in which a module
  156.  * is running.  It is used for the "flags" field of a ModuleAppInfo record.
  157.  */
  158. enum MAppFlags
  159.     {
  160.     afInternalDebug = 1,        // Application was compiled with internal debugging
  161.                                     // code enabled.
  162.     afModuleDebug     = 2,        // Application was compiled with module-debugging
  163.                                     // code enabled.
  164.     afDemoVersion     = 4        // This is a demo version of the application (freely
  165.                                     // distributable, some features disabled).
  166.     }; // MAppFlags
  167.  
  168.  
  169. /* This struct provides information about the application inside which a
  170.  * module has been loaded.
  171.  */
  172. struct ModuleAppInfo
  173.     {
  174.     Short     vers;            // Version number for this record (currently 1).
  175.     Short        pad;                // Unused (always 0).
  176.     uInteger  appID;            // Unique identifier for this application.
  177.     uInteger  appVers;        // Application version number.
  178.     FSSpec    appFile;        // Location of the application file.
  179.     Short         appRefnum;        // Refnum for the application's resource fork.
  180.     MAppFlags flags;            // Flags
  181.     }; // ModuleAppInfo
  182.  
  183.  
  184. /* This struct lists the callback functions available for manipulating
  185.  * modules themselves.
  186.  */
  187. struct ModMgrCalls
  188.     {
  189.     Short vers;    // Version number for this record (currently 1).
  190.     Short pad;    // Unused (always 0).
  191.     
  192.     ModuleID                (*FindModuleName)        (const char* name, uInteger minVers ENDP);
  193.     ModuleID                (*FindModuleID)        (uInteger id,      uInteger minVers ENDP);
  194.     const ModuleInfo* (*GetModInfo)            (pModuleID module ENDP);
  195.     OSErr                    (*OpenModFile)            (const FSSpec *file, pShort fileRefnum ENDP);
  196.     
  197.     ModuleEntryPoint  (*GetModuleEntry)        (pModuleID module, uInteger entryID ENDP);
  198.     ProcPtr                (*ModuleCallPrelude)    ( const ModuleEntryPoint *entry,
  199.                                                           OUT ModuleParamBlock *pb ENDP );
  200.     void                    (*ModuleCallEpilogue)( const ModuleEntryPoint *entry,
  201.                                                           const ModuleParamBlock *pb ENDP );
  202.     }; // ModMgrCalls
  203.  
  204.  
  205. // This enum defines some parameters for functions in the MemCalls table.
  206. enum AllocMode { amFreeStore,                  // Allocate on the C++ free store.
  207.                       amPtr,                          // Allocate a Memory Manager pointer.
  208.                       amHdl,                          // Allocate a Memory Manager handle.
  209.                       amTypeMask   = 0xFF,      // Mask for previous options.
  210.                       amFriendly   = 0x100,      // Modifier to disallow allocations
  211.                                                         // which would put us near to running
  212.                                                       // out of memory.
  213.                       amClear      = 0x200,      // Modifier to initialize storage to 0s.
  214.                       amErrIfNoMem = 0x400 }; // Modifier to signal a fatal error,
  215.                                                         // rather than returning nil, if
  216.                                                       // allocation fails.
  217.  
  218. #if defined (__SC__) || defined (__MWERKS__)
  219.     typedef long pAllocMode;
  220. #else // ndef __SC__
  221.     typedef AllocMode pAllocMode;
  222. #endif // else ndef __SC__
  223.  
  224.  
  225. /* This struct lists the callback functions available for memory allocation
  226.  * and management.
  227.  */
  228. struct MemCalls
  229.     {
  230.     Short vers;    // Version number for this record (currently 1).
  231.     Short pad;    // Unused (always 0).
  232.     
  233.     void*        (*AllocMem)            (uInteger size, pAllocMode mode ENDP);
  234.     void        (*DeallocMem)        (void* block,     pAllocMode mode ENDP);
  235.     uInteger (*MemAvailable)    ();
  236.     }; // MemCalls
  237.  
  238.  
  239. // This struct lists various utility callback functions.
  240. struct UtilCalls
  241.     {
  242.     Short vers;    // Version number for this record (currently 1).
  243.     Short pad;    // Unused (always 0).
  244.     
  245.     const char* (*GetRString)    (pShort rsrcID, pShort stringIndex ENDP);
  246.     void            (*LowerString) (IO char* string, Integer length ENDP);
  247.     }; // UtilCalls
  248.  
  249.  
  250. /* This struct lists the callback functions available for reporting error
  251.  * conditions.
  252.  */
  253. struct ErrorCalls
  254.     {
  255.     Short vers;    // Version number for this record (currently 1).
  256.     Short pad;    // Unused (always 0).
  257.     }; // ErrorCalls
  258.  
  259.  
  260. /* This struct lists the callback functions available for debugging purposes.
  261.  * These functions are only available if the application has been compiled for
  262.  * module debugging.
  263.  */
  264. struct DebugCalls
  265.     {
  266.     Short vers;    // Version number for this record (currently 1).
  267.     Short pad;    // Unused (always 0).
  268.     
  269.     void (*PrintToLog) (const char* message ENDP);
  270.     }; // DebugCalls
  271.  
  272.  
  273. /* This struct contains a set of function pointers into the application code
  274.  * which can be called from a plugin module.
  275.  */
  276. struct CallbackTbl
  277.     {
  278.     Short vers;                        // Version number for this record (currently 1).
  279.     Short pad;                        // Unused (always 0).
  280.             ModMgrCalls* modMgr; // Module Manager functions.
  281.             MemCalls*     mem;        // Memory allocation/deallocation functions.
  282.             UtilCalls*   util;    // Utility functions
  283.             ErrorCalls*  err;        // Error-logging functions.
  284.             DebugCalls*  dbg;        // Debugging functions; nil in non-debug builds.
  285.     const void*        extra1; // Unused (always nil).
  286.     const void*        extra2; // Unused (always nil).
  287.     const void*        extra3; // Unused (always nil).
  288.     }; // CallbackTbl
  289.  
  290.  
  291. /* This struct defines the parameter block which is passed as the first
  292.  * parameter to all module entry points.  An entry point may have additional
  293.  * parameters, depending on the specific function being called.
  294.  */
  295. struct ModuleParamBlock
  296.     {
  297.     Short vers;                         // Version number for this record (currently 1).
  298.     Short pad;                          // Unused (currently 0).
  299.     uInteger moduleRefcon;          // Module refcon value.
  300.     uInteger hookRefcon;             // Hook-specific refcon value.
  301.     const ModuleSysInfo* sys;    // Pointer to information about this machine.
  302.     const ModuleAppInfo* app;    // Pointer to information about the application.
  303.     const ModuleInfo*    mod;    // Pointer to information about this module.
  304.     const CallbackTbl*   calls;  // Pointer to table of callback functions.
  305.     const void*          extra1; // Unused (always nil).
  306.     const void*                extra2; // Unused (always nil);
  307.     const void*                extra3; // Unused (always nil);
  308.     }; // ModuleParamBlock
  309.  
  310.  
  311. // Values for the action parameter of a module's root entry routine.
  312. enum ModuleRootAction
  313.     {
  314.     mrLoad,        // Module is being loaded - return 1 if module initializes
  315.                     // successfully, 0 otherwise.
  316.     mrUnload,    // Module is being unloaded.  Function result is ignored.
  317.     mrFindEntry // Request for address of a specific entry point in the
  318.                     // module.  Return a ProcPtr, or nil if entry point isn't
  319.                     // available.
  320.     };
  321.  
  322. #ifdef __SC__
  323.     typedef    long    pModuleRootAction;
  324. #elif defined (__MWERKS__)
  325.     typedef    long    pModuleRootAction;
  326. #else
  327.     typedef    ModuleRootAction    pModuleRootAction;
  328. #endif
  329.  
  330. /* Prototype for a module's root entry point (the function at the beginning
  331.  * of the root code resource).
  332.  */
  333. Integer ModuleRoot(ModuleParamBlock *pb, pModuleRootAction action, Integer p1 ENDP);
  334.  
  335. typedef Integer (*ModuleRootProc)(ModuleParamBlock*, pModuleRootAction, Integer ENDP);
  336.  
  337. #endif // #ifndef MODULE_H